home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / pd / serien / purity / nr.44 / superviewpcq / docs / svsupport_ref_eng.doc < prev    next >
Text File  |  1995-01-28  |  29KB  |  1,253 lines
  1.  
  2.    $VER: SVSupport_Reference.doc V5.1 (29.10.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.           Andreas R. Kleinert,
  9.           Grube Hohe Grethe 23,
  10.           D-57074 Siegen,
  11.           Germany.
  12.  
  13.     Phone:  +49-271-331859 (weekdays after 18.00h)
  14.             +49-271-332147 (weekdays after 18.00h)
  15.     EMail:  Fido             Andreas Kleinert 2:2457/345.10
  16.             Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  17.  
  18.       If nothing else works, try one of these Fido-InterNet gateways:
  19.  
  20.             Andreas_Kleinert@p10.f345.n2457.z2.fido.sub.org (Germany)
  21.             Andreas_Kleinert@p10.f345.n2457.z2.fidonet.org  (US)
  22.  
  23.  
  24.    Here is a listing of all currently available functions of the
  25.    superviewsupport.library in an Autodoc-like style of description :
  26.  
  27.         SVSUP_GetMemList           ; since Version 1
  28.         SVSUP_FreeMemList
  29.         SVSUP_AddMemEntry
  30.         SVSUP_AllocMemEntry
  31.         SVSUP_CheckInterleaved
  32.         SVSUP_GetXAspect
  33.         SVSUP_GetYAspect
  34.         SVSUP_GetBitMapDepth
  35.         SVSUP_GetBitMapHeight
  36.         SVSUP_GetBodySize
  37.         SVSUP_GetStdScreenSize
  38.         SVSUP_GetBestModeID
  39.         SVSUP_CopyScreenToBuffer8   *** OBSOLETE : Use ScreenToOnePlane8
  40.         SVSUP_LoadControlPad       ; since Version 2
  41.         SVSUP_SaveControlPad
  42.         SVSUP_FreeControlPad
  43.         SVSUP_FindControlPad
  44.         SVSUP_BitPlaneToOnePlane8  ; since Version 3
  45.         SVSUP_OnePlaneToBitPlane8
  46.         SVSUP_ScreenToOnePlane8
  47.         SVSUP_ScreenToBitPlane8
  48.         SVSUP_DisplayGfxBuffer     ; since Version 4
  49.         SVSUP_UnDisplayGfxBuffer
  50.         SVSUP_FreeGfxBuffer
  51.         SVSUP_FindControlPadNoCase ; since Version 5
  52.         SVSUP_ModifyControlPad
  53.         SVSUP_AddControlPad
  54.  
  55. -----------------------------------------------------------------------------
  56.    Functions available since Version 1 :
  57. -----------------------------------------------------------------------------
  58.  
  59.    NAME
  60.         SVSUP_GetMemList
  61.  
  62.    SYNOPSIS
  63.  
  64.         APTR SVSUP_GetMemList(void)
  65.         D0   -$1e
  66.  
  67.    FUNCTION
  68.  
  69.         Allocates a handle for accessing a memory allocation list.
  70.  
  71.    INPUT(S)
  72.  
  73.         -
  74.  
  75.    RESULT
  76.  
  77.         A pointer to a new allocated Handle or NULL, if allocation failed.
  78.  
  79.    WARNING
  80.  
  81.         Test, if the result was NULL, or not !
  82.  
  83.    BUGS
  84.  
  85.         -
  86.  
  87.    SINCE
  88.  
  89.         ... version 1 of the superviewsupport.library.
  90.  
  91.    SEE ALSO
  92.  
  93.         SVSUP_FreeMemList
  94.  
  95. -----------------------------------------------------------------------------
  96.  
  97.    NAME
  98.         SVSUP_FreeMemList
  99.  
  100.    SYNOPSIS
  101.  
  102.         VOID SVSUP_FreeMemList(APTR handle)
  103.         D0   -$24              A1
  104.  
  105.    FUNCTION
  106.  
  107.        Frees all memory from the given memory allocation list
  108.        and also delocates the list itself !
  109.  
  110.    INPUT(S)
  111.  
  112.        handle - a valid handle
  113.  
  114.    RESULT
  115.  
  116.         -
  117.  
  118.    SINCE
  119.  
  120.         ... version 1 of the superviewsupport.library.
  121.  
  122.    SEE ALSO
  123.  
  124.         SVSUP_GetMemList
  125.  
  126. -----------------------------------------------------------------------------
  127.  
  128.    NAME
  129.         SVSUP_AddMemEntry
  130.  
  131.    SYNOPSIS
  132.  
  133.         ULONG SVSUP_AddMemEntry(APTR handle, APTR pointer)
  134.         D0    -$2a              A1           A2
  135.  
  136.    FUNCTION
  137.  
  138.         Adds an "AllocVec"ed memory pointer to the memory list,
  139.         to be remembered for delocation later.
  140.  
  141.    INPUT(S)
  142.  
  143.         handle  - a valid handle
  144.         pointer - a pointer to a chunk of memory, which has been
  145.                   allocated with Exec's AllocVec() function
  146.  
  147.    RESULT
  148.  
  149.         Boolean value : The memory will be freed immediately, if
  150.         remembering failed.
  151.  
  152.    BUGS
  153.  
  154.         -
  155.  
  156.    SINCE
  157.  
  158.         ... version 1 of the superviewsupport.library.
  159.  
  160.    SEE ALSO
  161.  
  162.         SVSUP_FreeMemList
  163.  
  164. -----------------------------------------------------------------------------
  165.  
  166.    NAME
  167.         SVSUP_AllocMemEntry
  168.  
  169.    SYNOPSIS
  170.  
  171.         APTR SVSUP_AllocMemEntry(APTR handle, size, type)
  172.         D0   -$30                A1           D0    D1
  173.  
  174.    FUNCTION
  175.  
  176.         Allocates memory just like AllocVec(), but remembers this
  177.         in the given memory allocation list.
  178.  
  179.    INPUT(S)
  180.  
  181.         handle - a valid handle
  182.         size   - needed size for the memory chunk
  183.         type   - "MEMF_"-specification of the memory type
  184.  
  185.    RESULT
  186.  
  187.         pointer to memory or NULL.
  188.  
  189.    BUGS
  190.  
  191.         -
  192.  
  193.    SINCE
  194.  
  195.         ... version 1 of the superviewsupport.library.
  196.  
  197.    SEE ALSO
  198.  
  199.         SVSUP_GetMemList, SVSUP_FreeMemList
  200.  
  201. -----------------------------------------------------------------------------
  202.  
  203.    NAME
  204.         SVSUP_CheckInterleaved
  205.  
  206.    SYNOPSIS
  207.  
  208.         ULONG SVSUP_CheckInterleaved(struct Screen *sc)
  209.         D0    -$36                   A1
  210.  
  211.    FUNCTION
  212.  
  213.         Is the BitMap of the given Screen of type "interleaved"
  214.         (possible since OS V39 with AGA) ?
  215.  
  216.    INPUT(S)
  217.  
  218.         sc - a valid Screen Pointer
  219.  
  220.    RESULT
  221.  
  222.         Boolean value.
  223.  
  224.    BUGS
  225.  
  226.         -
  227.  
  228.    SINCE
  229.  
  230.         ... version 1 of the superviewsupport.library.
  231.  
  232.    SEE ALSO
  233.  
  234.         -
  235.  
  236. -----------------------------------------------------------------------------
  237.  
  238.    NAME
  239.         SVSUP_GetXAspect
  240.  
  241.    SYNOPSIS
  242.  
  243.         UBYTE SVSUP_GetXAspect(struct Screen *sc)
  244.         D0    -$3c             A1
  245.  
  246.    FUNCTION
  247.  
  248.         Calculates an ILBM compatible XAspect-value for any ScreenMode.
  249.  
  250.    INPUT(S)
  251.  
  252.         sc - a valid Screen Pointer
  253.  
  254.    RESULT
  255.  
  256.         XAspect value for the given Screen.
  257.  
  258.    BUGS
  259.  
  260.         -
  261.  
  262.    SINCE
  263.  
  264.         ... version 1 of the superviewsupport.library.
  265.  
  266.    SEE ALSO
  267.  
  268.         SVSUP_GetXAspect
  269.  
  270. -----------------------------------------------------------------------------
  271.  
  272.    NAME
  273.         SVSUP_GetYAspect
  274.  
  275.    SYNOPSIS
  276.  
  277.         UBYTE SVSUP_GetYAspect(struct Screen *sc)
  278.         D0    -$42             A1
  279.  
  280.    FUNCTION
  281.  
  282.         Calculates an ILBM compatible YAspect-value for any ScreenMode.
  283.  
  284.    INPUT(S)
  285.  
  286.         sc - a valid Screen Pointer
  287.  
  288.    RESULT
  289.  
  290.         YAspect value for the given Screen.
  291.  
  292.    BUGS
  293.  
  294.         -
  295.  
  296.    SINCE
  297.  
  298.         ... version 1 of the superviewsupport.library.
  299.  
  300.    SEE ALSO
  301.  
  302.         SVSUP_GetXAspect
  303.  
  304. -----------------------------------------------------------------------------
  305.  
  306.    NAME
  307.         SVSUP_GetBitMapDepth
  308.  
  309.    SYNOPSIS
  310.  
  311.         ULONG SVSUP_GetBitMapDepth(struct Screen *sc)
  312.         D0    -$48                 A1
  313.  
  314.    FUNCTION
  315.  
  316.         Finds out the depth of the BitMap of a given Screen.
  317.         This is safer than accessing the various structures under V39+.
  318.  
  319.    INPUT(S)
  320.  
  321.         sc - a valid Screen Pointer
  322.  
  323.    RESULT
  324.  
  325.         depth of the Screen's BitMap.
  326.  
  327.    BUGS
  328.  
  329.         -
  330.  
  331.    SINCE
  332.  
  333.         ... version 1 of the superviewsupport.library.
  334.  
  335.    SEE ALSO
  336.  
  337.         SVSUP_GetBitMapHeight
  338.  
  339. -----------------------------------------------------------------------------
  340.  
  341.    NAME
  342.         SVSUP_GetBitMapHeight
  343.  
  344.    SYNOPSIS
  345.  
  346.         ULONG SVSUP_GetBitMapHeight(struct Screen *sc)
  347.         D0    -$4e                 A1
  348.  
  349.    FUNCTION
  350.  
  351.         Finds out the height of the BitMap of a given Screen.
  352.         This is safer than accessing the various structures under V39+.
  353.  
  354.    INPUT(S)
  355.  
  356.         sc - a valid Screen Pointer
  357.  
  358.    RESULT
  359.  
  360.         height of the Screen's BitMap.
  361.  
  362.    BUGS
  363.  
  364.         -
  365.  
  366.    SINCE
  367.  
  368.         ... version 1 of the superviewsupport.library.
  369.  
  370.    SEE ALSO
  371.  
  372.         SVSUP_GetBitMapDepth
  373.  
  374. -----------------------------------------------------------------------------
  375.  
  376.    NAME
  377.         SVSUP_GetBodySize
  378.  
  379.    SYNOPSIS
  380.  
  381.         ULONG SVSUP_GetBodySize(struct Screen *sc)
  382.         D0    -$54              A1
  383.  
  384.    FUNCTION
  385.  
  386.         This function calculates the size of a buffer to hold the
  387.         given Screen's BitMap.
  388.         As the name reflects, this buffer confirms to the needs
  389.         of a "BODY" (or ABIT) chunk for ILBM (or ACBM) Files.
  390.         No alignment things are done.
  391.  
  392.    INPUT(S)
  393.  
  394.         sc - a valid Screen Pointer
  395.  
  396.    RESULT
  397.  
  398.         NULL or an adequate SVERR-Errorcode.
  399.  
  400.    BUGS
  401.  
  402.         -
  403.  
  404.    SINCE
  405.  
  406.         ... version 1 of the superviewsupport.library.
  407.  
  408.    SEE ALSO
  409.  
  410.         -
  411.  
  412. -----------------------------------------------------------------------------
  413.  
  414.    NAME
  415.         SVSUP_GetStdScreenSize
  416.  
  417.    SYNOPSIS
  418.  
  419.         ULONG SVSUP_GetStdScreenSize(ULONG mode_id, ULONG *width,
  420.         D0    -$5a                   D0             A1
  421.  
  422.                                      ULONG *height)
  423.                                      A2
  424.  
  425.  
  426.    FUNCTION
  427.  
  428.         Gets the standard dimensions for a given ScreenMode.
  429.         For e.g. "PAL:HighRes", this would be 640 and 256.
  430.         The values are written into the supplied ULONGs.
  431.  
  432.         This function may FAIL !
  433.  
  434.    INPUT(S)
  435.  
  436.         sc - a valid Screen Pointer
  437.  
  438.    RESULT
  439.  
  440.         Boolean value.
  441.  
  442.    BUGS
  443.  
  444.         -
  445.  
  446.    SINCE
  447.  
  448.         ... version 1 of the superviewsupport.library.
  449.  
  450.    SEE ALSO
  451.  
  452.         SVSUP_SuperView
  453.  
  454. -----------------------------------------------------------------------------
  455.  
  456.    NAME
  457.         SVSUP_GetBestModeID
  458.  
  459.    SYNOPSIS
  460.  
  461.         ULONG SVSUP_GetBestModeID(ULONG width, ULONG height, ULONG depth)
  462.         D0    -$60                D0           D1            D2
  463.  
  464.    FUNCTION
  465.  
  466.         Returns the best ScreenMode ID for a hypothetical Screen with the
  467.         given dimensions.
  468.         Under V37 ECS is assumed, under V39 the appropriate Gfx-Library's
  469.         function is used for that.
  470.  
  471.    INPUT(S)
  472.  
  473.         width, height, depth - Screen dimension values
  474.  
  475.    RESULT
  476.  
  477.         a ModeID value.
  478.  
  479.    BUGS
  480.  
  481.         -
  482.  
  483.    SINCE
  484.  
  485.         ... version 1 of the superviewsupport.library.
  486.  
  487.    SEE ALSO
  488.  
  489.         -
  490.  
  491. -----------------------------------------------------------------------------
  492.  
  493.    NAME
  494.         SVSUP_CopyScreenToBuffer8   *** OBSOLETE : Use ScreenToOnePlane8
  495.  
  496.    SYNOPSIS
  497.  
  498.         ULONG SVSUP_CopyScreenToBuffer8(struct Screen *sc, UBYTE *buffer,
  499.         D0    -$66                      A1           A2
  500.  
  501.                                         ULONG width, ULONG height,
  502.                                         D0           D1
  503.  
  504.                                         ULONG depth)
  505.                                         D2
  506.  
  507.    FUNCTION
  508.  
  509.         *** You should use SVSUP_ScreenToOnePlane8() instead, which
  510.             is more easy to handle and uses this function, anyway ...
  511.  
  512.         This function copies the content of a common Intuition Screen
  513.         into a buffer in the "ChunkyPixel" (8 Bit) format.
  514.         The buffer itself (with size = width * height) has to be supplied.
  515.         The width, height and depth values (depth must be smaller than 8)
  516.         have to be supplied also. These are not read from the Screen.
  517.  
  518.         This function may FAIL.
  519.  
  520.    INPUT(S)
  521.  
  522.         sc     - a valid ScreenPointer
  523.         buffer - a pointer to a buffer with size = width * height
  524.         width  - Screen's Width
  525.         height - Screen's Height
  526.         depth  - Screen's Depth
  527.  
  528.    RESULT
  529.  
  530.         Boolean value.
  531.  
  532.    BUGS
  533.  
  534.         -
  535.  
  536.    SINCE
  537.  
  538.         ... version 1 of the superviewsupport.library.
  539.  
  540.    SEE ALSO
  541.  
  542.         SVSUP_SuperWrite
  543.  
  544. -----------------------------------------------------------------------------
  545.    Functions available since Version 2 :
  546. -----------------------------------------------------------------------------
  547.  
  548.    NAME
  549.         SVSUP_LoadControlPad
  550.  
  551.    SYNOPSIS
  552.  
  553.         ULONG SVSUP_LoadControlPad(UBYTE *filename, struct SV_ControlPad **pad)
  554.         D0    -$6c                 A1               A2
  555.  
  556.    FUNCTION
  557.  
  558.         Opens and reads a standard Configuration File for superview.library's
  559.         SVObjects, SVDrivers, etc.
  560.         It consists of Tooltype-like entries in the form :
  561.         <Name>=<Content> or <Keyword>, where each entry is built of one
  562.         line of the file.
  563.         All lines beginning with "/" or ";" or just blank lines are handled
  564.         as comments and are ignored.
  565.  
  566.         All ControlPads are chained in a single-linked List.
  567.         Remember to save the head-pointer to the List somewhere,
  568.         because it's needed for free'ing the List.
  569.  
  570.         Only READ-ACCESSES should be done to the list entries, but if you
  571.         want to add more entries to the list, note that all entries have
  572.         to be allocated with AllocVec() and delocated with FreeVec().
  573.  
  574.    INPUT(S)
  575.  
  576.         filename - a FileName for AmigaDOS
  577.         pad      - a pointer to a ControlPad-Structure pointer
  578.  
  579.    RESULT
  580.  
  581.         Boolean value.
  582.  
  583.         If the function returned FALSE, pad will also be NULL.
  584.  
  585.    BUGS
  586.  
  587.         SVSUP_FindControlPad, SVSUP_SaveControlPad, SVSUP_FreeControlPad
  588.  
  589.    SINCE
  590.  
  591.         ... version 2 of the superviewsupport.library.
  592.  
  593.    SEE ALSO
  594.  
  595.         -
  596.  
  597. -----------------------------------------------------------------------------
  598.  
  599.    NAME
  600.         SVSUP_SaveControlPad
  601.  
  602.    SYNOPSIS
  603.  
  604.         ULONG SVSUP_SaveControlPad(UBYTE *filename, struct SV_ControlPad *pad)
  605.         D0    -$72                 A1               A2
  606.  
  607.    FUNCTION
  608.  
  609.         Writes a standard Configuration File for superview.library's
  610.         SVObjects, SVDrivers, etc.
  611.  
  612.         You have to supply your own ControlPad-List (or one supplied from
  613.         SVSUP_LoadControlPad).
  614.  
  615.    INPUT(S)
  616.  
  617.         filename - a FileName for AmigaDOS
  618.         pad      - a pointer to a ControlPad-Structure (List-Head)
  619.  
  620.    RESULT
  621.  
  622.         Boolean value.
  623.  
  624.    BUGS
  625.  
  626.         -
  627.  
  628.    SINCE
  629.  
  630.         ... version 2 of the superviewsupport.library.
  631.  
  632.    SEE ALSO
  633.  
  634.         SVSUP_FindControlPad, SVSUP_LoadControlPad, SVSUP_FreeControlPad
  635.  
  636. -----------------------------------------------------------------------------
  637.  
  638.    NAME
  639.         SVSUP_FreeControlPad
  640.  
  641.    SYNOPSIS
  642.  
  643.         ULONG SVSUP_FreeControlPad(struct SV_ControlPad *pad)
  644.         D0    -$78                 A1
  645.  
  646.    FUNCTION
  647.  
  648.         Frees a single-chained list of ControlPads, which has been
  649.         allocated and initialized via SVSUP_LoadControlPad() before.
  650.  
  651.         If you want to free your own, self-created ControlPad lists,
  652.         note that all entries have to be allocated with AllocVec() and
  653.         delocated with FreeVec().
  654.  
  655.    INPUT(S)
  656.  
  657.         pad      - a pointer to a ControlPad-Structure (List-Head)
  658.  
  659.    RESULT
  660.  
  661.         Boolean value.
  662.  
  663.         (returns FALSE when pad is a NULL pointer)
  664.  
  665.    BUGS
  666.  
  667.         -
  668.  
  669.    SINCE
  670.  
  671.         ... version 2 of the superviewsupport.library.
  672.  
  673.    SEE ALSO
  674.  
  675.         SVSUP_FindControlPad, SVSUP_SaveControlPad, SVSUP_LoadControlPad
  676.  
  677. -----------------------------------------------------------------------------
  678.  
  679.    NAME
  680.         SVSUP_FindControlPad
  681.  
  682.    SYNOPSIS
  683.  
  684.         ULONG SVSUP_FindControlPad(struct SV_ControlPad *pad,
  685.         D0    -$7e                 A1
  686.  
  687.                                    UBYTE *name,
  688.                                    A2
  689.  
  690.                                    UBYTE **content)
  691.                                    A3
  692.  
  693.    FUNCTION
  694.  
  695.         A ControlPad-List consists of Tooltype-like entries in the form :
  696.         <Name>=<Content> or <Keyword>.
  697.  
  698.         This function scans through such a list and searches for the
  699.         Content of an Entry with a specific name.
  700.         For Keywords the result is TRUE, but the Content pointer will
  701.         be NULL nevertheless.
  702.  
  703.         Searching IS case-sensitive !
  704.         Only READ-ACCESS to the content is allowed.
  705.  
  706.    INPUT(S)
  707.  
  708.         pad      - a pointer to a ControlPad-Structure (List-Head)
  709.         name     - the name of the entry to search for
  710.         content  - a pointer to a string pointer
  711.                    (the string pointer will be initialized with a pointer
  712.                     to the Content or NULL)
  713.  
  714.    RESULT
  715.  
  716.         Boolean value.
  717.  
  718.    BUGS
  719.  
  720.         -
  721.  
  722.    SINCE
  723.  
  724.         ... version 2 of the superviewsupport.library.
  725.  
  726.    SEE ALSO
  727.  
  728.         SVSUP_LoadControlPad, SVSUP_SaveControlPad, SVSUP_FreeControlPad
  729.  
  730. -----------------------------------------------------------------------------
  731.    Functions available since Version 3 :
  732. -----------------------------------------------------------------------------
  733.  
  734.    NAME
  735.         SVSUP_BitPlaneToOnePlane8
  736.  
  737.    SYNOPSIS
  738.  
  739.         ULONG SVSUP_BitPlaneToOnePlane8(struct SV_GfxBuffer *gfxb,
  740.         D0    -$84                      A1
  741.  
  742.                                         struct SV_GfxBuffer **destgfxb)
  743.                                         A2
  744.  
  745.    FUNCTION
  746.  
  747.         This function takes a GfxBuffer of type BITPLANE and creates
  748.         a GfxBuffer of type ONEPLANE out of it. This works with upto
  749.         8 Bit ColorDepth (256 Colors).
  750.  
  751.         The new GfxBuffer has to be given free by the user.
  752.  
  753.    INPUT(S)
  754.  
  755.         gfx      - a pointer to the Source GfxBuffer (BITPLANE)
  756.         destgfx  - a pointer to a pointer for the Destination
  757.                    GfxBuffer (ONEPLANE)
  758.  
  759.    RESULT
  760.  
  761.         NULL or a SVERR-Errorcode.
  762.  
  763.    BUGS
  764.  
  765.         -
  766.  
  767.    SINCE
  768.  
  769.         ... version 3 of the superviewsupport.library.
  770.  
  771.    SEE ALSO
  772.  
  773.         SVSUP_OnePlaneToBitPlane8
  774.  
  775. -----------------------------------------------------------------------------
  776.    NAME
  777.         SVSUP_OnePlaneToBitPlane8
  778.  
  779.    SYNOPSIS
  780.  
  781.         ULONG SVSUP_OnePlaneToBitPlane8(struct SV_GfxBuffer *gfxb,
  782.         D0    -$8a                      A1
  783.  
  784.                                         struct SV_GfxBuffer **destgfxb)
  785.                                         A2
  786.  
  787.    FUNCTION
  788.  
  789.         This function takes a GfxBuffer of type ONEPLANE and creates
  790.         a GfxBuffer of type BITPLANE out of it. This works with upto
  791.         8 Bit ColorDepth (256 Colors).
  792.  
  793.         The new GfxBuffer has to be given free by the user.
  794.  
  795.    INPUT(S)
  796.  
  797.         gfx      - a pointer to the Source GfxBuffer (ONEPLANE)
  798.         destgfx  - a pointer to a pointer for the Destination
  799.                    GfxBuffer (BITPLANE)
  800.  
  801.    RESULT
  802.  
  803.         NULL or a SVERR-Errorcode.
  804.  
  805.    BUGS
  806.  
  807.         -
  808.  
  809.    SINCE
  810.  
  811.         ... version 3 of the superviewsupport.library.
  812.  
  813.    SEE ALSO
  814.  
  815.         SVSUP_BitPlaneToOnePlane8
  816.  
  817. -----------------------------------------------------------------------------
  818.  
  819.    NAME
  820.         SVSUP_ScreenToOnePlane8
  821.  
  822.    SYNOPSIS
  823.  
  824.         ULONG SVSUP_ScreenToOnePlane8(struct Screen *sc,
  825.         D0    -$90                    A1
  826.  
  827.                                       struct SV_GfxBuffer **destgfxb)
  828.                                       A2
  829.  
  830.    FUNCTION
  831.  
  832.         This function takes an Intuition Screen and creates
  833.         a GfxBuffer of type ONEPLANE out of it. This works with upto
  834.         8 Bit ColorDepth (256 Colors).
  835.  
  836.         The new GfxBuffer has to be given free by the user.
  837.  
  838.    INPUT(S)
  839.  
  840.         gfx      - a pointer to an Intuition Screen
  841.         destgfx  - a pointer to a pointer for the Destination
  842.                    GfxBuffer (ONEPLANE)
  843.  
  844.    RESULT
  845.  
  846.         NULL or a SVERR-Errorcode.
  847.  
  848.    BUGS
  849.  
  850.         -
  851.  
  852.    SINCE
  853.  
  854.         ... version 3 of the superviewsupport.library.
  855.  
  856.    SEE ALSO
  857.  
  858.         SVSUP_ScreenToBitPlane8
  859.  
  860. -----------------------------------------------------------------------------
  861.    NAME
  862.         SVSUP_ScreenToBitPlane8
  863.  
  864.    SYNOPSIS
  865.  
  866.         ULONG SVSUP_ScreenToBitPlane8(struct Screen *sc,
  867.         D0    -$96                    A1
  868.  
  869.                                       struct SV_GfxBuffer **destgfxb)
  870.                                       A2
  871.  
  872.    FUNCTION
  873.  
  874.         This function takes an Intuition Screen and creates
  875.         a GfxBuffer of type BITPLANE out of it. This works with upto
  876.         8 Bit ColorDepth (256 Colors).
  877.  
  878.         The new GfxBuffer has to be given free by the user.
  879.  
  880.    INPUT(S)
  881.  
  882.         gfx      - a pointer to an Intuition Screen
  883.         destgfx  - a pointer to a pointer for the Destination
  884.                    GfxBuffer (BITPLANE)
  885.  
  886.    RESULT
  887.  
  888.         NULL or a SVERR-Errorcode.
  889.  
  890.    BUGS
  891.  
  892.         -
  893.  
  894.    SINCE
  895.  
  896.         ... version 3 of the superviewsupport.library.
  897.  
  898.    SEE ALSO
  899.  
  900.         SVSUP_ScreenToOnePlane8
  901.  
  902. -----------------------------------------------------------------------------
  903.    Functions available since Version 4 :
  904. -----------------------------------------------------------------------------
  905.  
  906.    NAME
  907.         SVSUP_DisplayGfxBuffer
  908.  
  909.    SYNOPSIS
  910.  
  911.         ULONG SVSUP_DisplayGfxBuffer(struct SVSUP_DisplayHandle *disphandle)
  912.         D0    -$9c                   A1
  913.  
  914.    FUNCTION
  915.  
  916.         This function allows displaying of GfxBuffers, e.g. for
  917.         test-purposes.
  918.  
  919.         This will may you, if you simply want to check the results
  920.         of self-created GfxBuffers or compare the results of
  921.         a GfxBuffer-conversion via e.g. SVSUP_OnePlaneToBitPlane8.
  922.  
  923.         The following code is quite senseless, because it is much easier
  924.         to use SVL_DisplayGfxBuffer() instead, but it demonstrates
  925.         quite good, how this function may be used (and _this_ example
  926.         definitely works ...) :
  927.  
  928.         ULONG GfxBufferShow(char *filename)
  929.          {
  930.           ULONG                       retval        = SVERR_NO_ERROR;
  931.           APTR                        handle        = N;
  932.           struct SVSUP_DisplayHandle *displayhandle = N;
  933.  
  934.           displayhandle = AllocVec(sizeof(struct SVSUP_DisplayHandle), MEMF_CLEAR|MEMF_PUBLIC);
  935.           if(displayhandle)
  936.            {
  937.             SVL_GetGlobalDriver(&displayhandle->SVDriverNode, N);
  938.  
  939.             handle = SVL_AllocHandle(N);
  940.             if(handle)
  941.              {
  942.               if(!(retval = SVL_InitHandleAsDOS(handle, N)))
  943.                {
  944.                 displayhandle->WinIDCMP = IDCMP_MOUSEBUTTONS;
  945.                 displayhandle->ScrType  = CUSTOMSCREEN;
  946.  
  947.                             retval = SVL_ReadToGfxBuffer(handle, filename);
  948.                 if(!retval) retval = SVL_GetGfxBuffer(   handle, &displayhandle->SVGfxBuffer, N);
  949.  
  950.                 if(!retval && displayhandle->SVGfxBuffer)
  951.                  {
  952.                   retval = SVSUP_DisplayGfxBuffer(displayhandle);
  953.                   if(!retval)
  954.                    {
  955.                     if(displayhandle->Window)
  956.                      {
  957.                       WaitPort(displayhandle->Window->UserPort);
  958.                      }
  959.                    }
  960.  
  961.                   SVSUP_UnDisplayGfxBuffer(displayhandle);
  962.                  }
  963.                }
  964.  
  965.               SVL_FreeHandle(handle);
  966.  
  967.              }else retval = SVERR_NO_HANDLE;
  968.  
  969.             FreeVec(displayhandle);
  970.  
  971.            }else retval = SVERR_NO_MEMORY;
  972.  
  973.           return(retval);
  974.          }
  975.  
  976.  
  977.         The Handle has to be allocated and initialized before passing it
  978.         to this function. After usage - and after calling SVSUP_UnDisplay-
  979.         GfxBuffer() - it has still to be delocated.
  980.  
  981.         You do not need (or must) initialize all fields of the Handle
  982.         structure, but set them to NULL, if you do not (or must not).
  983.         It is suggested, that you'll use AllocMem/AllocVec() with the
  984.         MEMF_CLEAR flag.
  985.  
  986.         Initialize at least the following fields :
  987.  
  988.           - Version              (currently 4)
  989.           - SVGfxBuffer          (the GfxBuffer)
  990.           - SVDriverNode         (as returned by SVL_GetGlobalDriver)
  991.  
  992.         Optionally initialize the following fields :
  993.  
  994.           - WinIDCMP
  995.           - WinFlags
  996.           - ScrType
  997.  
  998.         After calling SVSUP_DisplayGfxBuffer(), but before
  999.         SVSUP_UnDisplayGfxBuffer() you may use the following fields
  1000.         for read-only purposes ::
  1001.  
  1002.           - Window;
  1003.           - Screen;
  1004.  
  1005.  
  1006.         All values are used and have to be interpreted just like the
  1007.         corresponding parameters of the similar SVL_/SVO_ or SVD_
  1008.         function calls :
  1009.         If you do not supply values for ScreenType, WindowIDCMP and
  1010.         WindowFlags, default-values will be used instead.
  1011.  
  1012.    INPUT(S)
  1013.  
  1014.         displayhandle - a handle, as defined in "superviewsupport.h".
  1015.                         Has to be allocated and initalized by the User !!
  1016.  
  1017.    RESULT
  1018.  
  1019.         NULL or a SVERR-Errorcode.
  1020.  
  1021.    BUGS
  1022.  
  1023.         -
  1024.  
  1025.    SINCE
  1026.  
  1027.         ... version 4 of the superviewsupport.library.
  1028.  
  1029.    SEE ALSO
  1030.  
  1031.         SVSUP_UnDisplayGfxBuffer
  1032.  
  1033. -----------------------------------------------------------------------------
  1034.  
  1035.    NAME
  1036.         SVSUP_UnDisplayGfxBuffer
  1037.  
  1038.    SYNOPSIS
  1039.  
  1040.         ULONG SVSUP_UnDisplayGfxBuffer(struct SVSUP_DisplayHandle *disphandle)
  1041.         D0    -$a2                     A1
  1042.  
  1043.    FUNCTION
  1044.  
  1045.         This function closes a display, which has been opened via
  1046.         SVSUP_DisplayGfxBuffer() before.
  1047.  
  1048.         All temporary buffers etc. will be delocated, then.
  1049.         The supplied GfxBuffer and the Handle itself will be left intact.
  1050.  
  1051.         This call requires a valid displayhandle (which has been passed
  1052.         to SVSUP_DisplayGfxBuffer before).
  1053.  
  1054.         See SourceCode-example under SVSUP_DisplayGfxBuffer().
  1055.  
  1056.    INPUT(S)
  1057.  
  1058.         displayhandle - a handle, as defined in "superviewsupport.h".
  1059.                         Has still to be delocated by the User !!
  1060.  
  1061.    RESULT
  1062.  
  1063.         -
  1064.  
  1065.    BUGS
  1066.  
  1067.         -
  1068.  
  1069.    SINCE
  1070.  
  1071.         ... version 4 of the superviewsupport.library.
  1072.  
  1073.    SEE ALSO
  1074.  
  1075.         SVSUP_DisplayGfxBuffer
  1076.  
  1077. -----------------------------------------------------------------------------
  1078.  
  1079.    NAME
  1080.         SVSUP_FreeGfxBuffer
  1081.  
  1082.    SYNOPSIS
  1083.  
  1084.         ULONG SVSUP_FreeGfxBuffer(struct SV_GfxBuffer *gfxbuffer)
  1085.         D0    -$a8                A1
  1086.  
  1087.    FUNCTION
  1088.  
  1089.         Use this function to free GfxBuffers, which are not related to
  1090.         any SVObject-Handles.
  1091.  
  1092.         E.g. any of the SVSUP_ScreenToXXXPlane() and SVSUP_XXXPlaneToXXXPlane()
  1093.         functions produce GfxBuffer, which have to be given free either
  1094.         via separate FreeVec() calls for the ImageData-Buffer and for
  1095.         the GfxBuffer itself or just by calling this function and then
  1096.         forgetting about it.
  1097.  
  1098.         Do not try to free buffers, which will already be freed via the
  1099.         next SVL_FreeHandle call.
  1100.         These are Buffers, which are returned by SVL_GetGfxBuffer().
  1101.  
  1102.    INPUT(S)
  1103.  
  1104.         gfxbuffer - a valid pointer to a "stand-alone" GfxBuffer
  1105.  
  1106.    RESULT
  1107.  
  1108.         -
  1109.  
  1110.    BUGS
  1111.  
  1112.         -
  1113.  
  1114.    SINCE
  1115.  
  1116.         ... version 4 of the superviewsupport.library.
  1117.  
  1118.    SEE ALSO
  1119.  
  1120.         SVSUP_ScreenToXXXPlane(), SVSUP_XXXPlaneToXXXPlane()
  1121.  
  1122.         (XXX = (Bit | One)
  1123.  
  1124. -----------------------------------------------------------------------------
  1125.    Functions available since Version 5 :
  1126. -----------------------------------------------------------------------------
  1127.  
  1128.    NAME
  1129.         SVSUP_FindControlPadNoCase
  1130.  
  1131.    SYNOPSIS
  1132.  
  1133.         ULONG SVSUP_FindControlPadNoCase(struct SV_ControlPad *pad,
  1134.         D0    -$ae                       A1
  1135.  
  1136.                                          UBYTE *name,
  1137.                                          A2
  1138.  
  1139.                                          UBYTE **content)
  1140.                                          A3
  1141.  
  1142.    FUNCTION
  1143.  
  1144.         like SVSUP_FindControlPad(), not not case-sensitive.
  1145.  
  1146.    INPUT(S)
  1147.  
  1148.         like SVSUP_FindControlPad()
  1149.  
  1150.    RESULT
  1151.  
  1152.         like SVSUP_FindControlPad()
  1153.  
  1154.    SINCE
  1155.  
  1156.         ... version 5 of the superviewsupport.library.
  1157.  
  1158.    SEE ALSO
  1159.  
  1160.         SVSUP_FindControlPad
  1161.  
  1162. -----------------------------------------------------------------------------
  1163.    NAME
  1164.         SVSUP_ModifyControlPad
  1165.  
  1166.    SYNOPSIS
  1167.  
  1168.         ULONG SVSUP_ModifyControlPad(struct SV_ControlPad *pad,
  1169.         D0    -$b4                   A1
  1170.  
  1171.                                      UBYTE *name,
  1172.                                      A2
  1173.  
  1174.                                      UBYTE *content,
  1175.                                      A3
  1176.  
  1177.                                      ULONG bool)
  1178.                                      D1
  1179.  
  1180.    FUNCTION
  1181.  
  1182.         Modifies an existing ControlPad entry, if exists.
  1183.         Returns error, if it does not exist.
  1184.  
  1185.         May be switched between case-sensitive and case-insensitive mode.
  1186.  
  1187.    INPUT(S)
  1188.  
  1189.         pad      - a pointer to a ControlPad-Structure (List-Head)
  1190.         name     - the name of the entry to search for
  1191.         content  - string pointer to new content or NULL
  1192.         bool     - case-sensitive ?
  1193.  
  1194.    RESULT
  1195.  
  1196.         Boolean value.
  1197.  
  1198.    SINCE
  1199.  
  1200.         ... version 5 of the superviewsupport.library.
  1201.  
  1202.    SEE ALSO
  1203.  
  1204.         SVSUP_AddControlPad
  1205.  
  1206. -----------------------------------------------------------------------------
  1207.  
  1208.    NAME
  1209.         SVSUP_AddControlPad
  1210.  
  1211.    SYNOPSIS
  1212.  
  1213.         ULONG SVSUP_AddControlPad(struct SV_ControlPad *pad,
  1214.         D0    -$ba                A1
  1215.  
  1216.                                   UBYTE *name,
  1217.                                   A2
  1218.  
  1219.                                   UBYTE *content,
  1220.                                   A3
  1221.  
  1222.                                   ULONG bool)
  1223.                                   D1
  1224.  
  1225.    FUNCTION
  1226.  
  1227.         Adds a new ControlPad entry or modifies one, if already exists.
  1228.         May return an error (no memory, etc.)
  1229.  
  1230.         May be switched between case-sensitive and case-insensitive mode.
  1231.  
  1232.    INPUT(S)
  1233.  
  1234.         pad      - a pointer to a ControlPad-Structure (List-Head)
  1235.         name     - the name of the entry to search for
  1236.         content  - string pointer to content or NULL
  1237.         bool     - case-sensitive ?
  1238.  
  1239.    RESULT
  1240.  
  1241.         Boolean value.
  1242.  
  1243.    SINCE
  1244.  
  1245.         ... version 5 of the superviewsupport.library.
  1246.  
  1247.    SEE ALSO
  1248.  
  1249.         SVSUP_ModifyControlPad
  1250.  
  1251. -----------------------------------------------------------------------------
  1252.  
  1253.